<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>mpt_call_lcp</title>
<style type="text/css">
	body {background-color: white; color: black; font-family:sans-serif; font-size:medium;}
	a:link {color: #3300ff;}
	a:visited {color: #663399;}
	a:hover {color:#0099ff;}
	a:active {color: #0066cc;}
	a.button {text-decoration:none;}
	
	table.nav  {background-color: #dbddff;}
	table.body {margin-top:2ex; margin-bottom:2ex;}
	table.programlistingindent {margin-left:32px;}
	
	img { margin-bottom:0px; margin-top:0px;}
	tt {margin-left:0.5em; margin-right:0.5em; font-weight:lighter;}
	
	p {margin-top:0ex;}
	p.synopsis {margin-left:32px;}
	p.programlistingindent {margin-left:32px;}
	p.citetitle {margin-left:2em;}
	
	ul ul {list-style-type:square;}
	ul li p {margin-top:0ex; margin-bottom:.5ex; padding:0}
	ol li p {margin-top:0ex; margin-bottom:.5ex; padding:0}
	
	h1.reftitle {color:#a90000;}
	h1.reftitle {font-size:3.7ex; margin-top:0; margin-bottom:0; font-weight:bold}
	h1.title {color:black; font-size:4ex; margin-top:1ex; font-weight:bold}
	h2.title {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:3ex}
	h3.title {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2.5ex}
	h4.title {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2ex}
	h2 {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2.5ex}
	h3 {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2ex} 
	
	pre.programlisting {margin-left:32px;}
	pre.synopsis {margin-left:32px;}
	
	
	.categorytitle {margin-top:8px; padding-top:0px;}
	.categorylist {background-color: #e1e6f2;}
 	</style>
</head>
<body>
<a name="top_of_page"></a><p style="font-size:1px;"></p>
<h1 class="reftitle">mpt_call_lcp</h1>
<h2>Purpose</h2>
<p>A gateway function to LCP solver (without errorchecks)</p>
<h2>Syntax</h2>
<pre class="synopsis">R = mpt_call_lcp(S)</pre>
<h2>Description</h2>
<p></p>
		The function implements calls to LCP solver based on the optimization problem to be solved.
        Supported problems are LCP, LP, and QP.
        
        If the problem type is LCP, then LCP mex-function is called directly. Otherwise a transformation
        to LCP problem is performed. Assume that QP/LP is written in a form
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp41.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp41.png"></p>
        We want to transform it to 
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp42.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp42.png"></p>
        which corresponds to the following LCP
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp43.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp43.png"></p>
        where 
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp44.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp44.png"></p>
        
        If LP or QP contains equality constraints, these are removed first. It is required that the system of 
        linear equations <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp1.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp1.png"> is consistent, i.e. no linearly dependent rows are found and 
        the number of equalities is strictly less than number of variables.
        The principle is based on factorizing equality constraints <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp2.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp2.png"> in basic <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp3.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp3.png">
        and non-basic variables <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp4.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp4.png">, i.e.
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp45.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp45.png"></p>
        which gives
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp46.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp46.png"></p>
        where the index sets <tt>Bc</tt>, <tt>Nc</tt> denote the columns from which factored system is built. 
        The factored submatrix <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp5.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp5.png"> must be invertible in order to express basic variables as 
        a function of non-basic variables, i.e.
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp47.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp47.png"></p>
        With the substitution
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp48.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp48.png"></p>
        and 
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp49.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp49.png"></p>
        the  relation between basic and non-basic variables is simplified to
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp50.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp50.png"></p>
        The above QP/LP problem <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp6.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp6.png"> can be expressed only in non-basic variables <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp7.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp7.png"> as follows:
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp51.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp51.png"></p>        
        where 
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp52.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp52.png"></p>
        Original solution to QP problem <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp8.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp8.png"> can be obtained via relation <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp9.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp9.png">.
        
        Problem <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp10.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp10.png"> can be transformed to <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp11.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp11.png"> 
        effectively when considering the rank of the matrix <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp12.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp12.png">.
        If the rank of matrix <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp13.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp13.png"> is less than the number of inequalities in <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp14.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp14.png"> 
        vector <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp15.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp15.png"> can be expressed as a difference of two positive numbers, i.e.
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp53.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp53.png"></p>
        With the substitution
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp54.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp54.png"></p>
        and putting back to <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp16.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp16.png"> we get
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp55.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp55.png"></p>        
        which is a form equivalent to <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp17.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp17.png">.
        If the rank of matrix <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp18.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp18.png"> is greater or equal than the number of inequalities in <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp19.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp19.png">, 
        we can factorize the matrix <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp20.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp20.png"> rowwise
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp56.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp56.png"></p>
        where <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp21.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp21.png">, <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp22.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp22.png"> are index sets corresponding to rows from which submatrices are built. The factored system
        <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp23.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp23.png"> can be written as
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp57.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp57.png"></p>
        where the matrix <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp24.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp24.png"> form by rows in the set <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp25.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp25.png"> must be invertible. Using the substitution 
        <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp58.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp58.png"></p>
        the system <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp26.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp26.png"> can be rewritten in variable <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp27.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp27.png">
        
      <p class="programlistingindent"><img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp59.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp59.png"></p>
        which is equivalent to <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp28.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp28.png">.
        
	<h2>Input Arguments</h2>
<table cellspacing="0" class="body" cellpadding="4" border="0" width="100%">
<colgroup>
<col width="31%">
<col width="69%">
</colgroup>
<tbody><tr valign="top">
<td><tt>S</tt></td>
<td>
<p></p>Structure of the Opt class.<p>
	    		Class: <tt>struct</tt><p></p><tr valign="top">
<td><tt>S.H</tt></td>
<td>
<p></p>Quadratic part of the objective function.<p>
	    		Class: <tt>double</tt></p>
<p>
	    		Default: []</p>
</td>
</tr><tr valign="top">
<td><tt>S.f</tt></td>
<td>
<p></p>Linear part of the objective function.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.A</tt></td>
<td>
<p></p>Linear part of the inequality constraints <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp29.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp29.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.b</tt></td>
<td>
<p></p>Right hand side of the inequality constraints <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp30.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp30.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.Ae</tt></td>
<td>
<p></p>Linear part of the equality constraints <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp31.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp31.png">.<p>
	    		Class: <tt>double</tt></p>
<p>
	    		Default: []</p>
</td>
</tr><tr valign="top">
<td><tt>S.be</tt></td>
<td>
<p></p>Right hand side of the equality constraints <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp32.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp32.png">.<p>
	    		Class: <tt>double</tt></p>
<p>
	    		Default: []</p>
</td>
</tr><tr valign="top">
<td><tt>S.lb</tt></td>
<td>
<p></p>Lower bound for the variables <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp33.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp33.png">.<p>
	    		Class: <tt>double</tt></p>
<p>
	    		Default: []</p>
</td>
</tr><tr valign="top">
<td><tt>S.ub</tt></td>
<td>
<p></p>Upper bound for the variables <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp34.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp34.png">.<p>
	    		Class: <tt>double</tt></p>
<p>
	    		Default: []</p>
</td>
</tr><tr valign="top">
<td><tt>S.M</tt></td>
<td>
<p></p>Data matrix for linear-complementarity problem <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp35.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp35.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.q</tt></td>
<td>
<p></p>Right hand side vector for linear-complementarity problem <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp36.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp36.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.n</tt></td>
<td>
<p></p>Problem dimension (number of variables).<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.m</tt></td>
<td>
<p></p>Number of inequalities in <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp37.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp37.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.me</tt></td>
<td>
<p></p>Number of equalities in <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp38.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp38.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.problem_type</tt></td>
<td>
<p></p>A string specifying the problem to be solved (only LP, QP and LCP problems are allowed).<p>
	    		Class: <tt>char</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.routine</tt></td>
<td>
<p></p>An integer specifying which subroutine to use for factorization. For details, see help for LCP solver.
                    <ul>
                        
                  <li>The number 0 indicates to use fast recursive factorization based on rank-1 updates from LUMOD package. </li>
                        
                  <li>The number 1 indicates to use LU factorization based on DGESV routine of LAPACK. </li>
                        
                  <li>The number 2 indicates to use QR factorization based on DGELS routine of LAPACK. </li>
                    
               </ul>
                
            <p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>S.test</tt></td>
<td>
<p></p>Call (false) or not to call (true) MPT global settings.<p>
	    		Class: <tt>logical</tt></p>
<p>
	    		Default: false</p>
</td>
</tr><p></p></p>
</td>
</tr></tbody>
</table>
<h2>Output Arguments</h2>
<table cellspacing="0" class="body" cellpadding="4" border="0" width="100%">
<colgroup>
<col width="31%">
<col width="69%">
</colgroup>
<tbody><tr valign="top">
<td><tt>R</tt></td>
<td>
<p></p>Result structure<p>
	    		Class: <tt>struct</tt><p></p><tr valign="top">
<td><tt>R.xopt</tt></td>
<td>
<p></p>The optimal values for variable <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp39.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp39.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>R.lambda</tt></td>
<td>
<p></p>The optimal values for variable <img src="../../../../fig/mpt/modules/solvers/mpt_call_lcp40.png" alt="../../../../fig/mpt/modules/solvers/mpt_call_lcp40.png">.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>R.obj</tt></td>
<td>
<p></p>If the LCP problem was created by conversion from LP/QP, this value represent the optimal cost of the appropriate LP/QP.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>R.exitflag</tt></td>
<td>
<p></p>An integer value that informs if the result was feasible (1), or otherwise (different from 1).<p>
	    		Class: <tt>double</tt></p>
</td>
</tr><tr valign="top">
<td><tt>R.how</tt></td>
<td>
<p></p>A string that informs if the result was feasible ('ok'), or if any problem appeared through optimization.<p>
	    		Class: <tt>char</tt></p>
</td>
</tr><p></p></p>
</td>
</tr></tbody>
</table>
<h2>References</h2>
<p class="citetitle">[1] 
	Stephen Boyd and Lieven Vandenberghe: Convex Optimization; Cambridge University Press
</p>
<p class="citetitle">[2] 
	Richard W. Cottle, Jong-Shi Pang, Richard E. Stone: Linear complementarity problem, Academic Press Inc. 1992
</p>
<h2>See Also</h2>
<a href="./mpt_solve.html">mpt_solve</a><p></p>
<table class="nav" summary="Navigation aid" border="0" width="100%" cellpadding="0" cellspacing="0"><tr valign="top">
<td align="left" width="20">
<a href="mpt_call_nag.html" class="button">&#9664;</a>  </td>
<td align="left">mpt_call_nag</td>
<td>  </td>
<td align="right">mpt_call_mpqp</td>
<td align="right" width="20"><a href="mpt_call_mpqp.html" class="button">&#9654;</a></td>
</tr></table>
<br><p>©  <b>2010-2013</b>     Martin Herceg: ETH Zurich,    <a href="mailto:herceg@control.ee.ethz.ch">herceg@control.ee.ethz.ch</a></p>
</body>
</html>
